Module 0: Lecture Notes 1

Introduction to Version Control

Git is, without any doubt, the most popular version control system. Ironically, there are other version control systems easier to learn and to use, but, despite that, Git is the favorite option for developers, which is quite clarifying about the powerfulness of Git (Loeliger and McCullough 2012; Blischak, Davenport, and Wilson 2016; McQuaid 2014).

Git has become the de-facto tool used for distributed version control. For this reason it is necessary for aspiring data scientists, machine learning and Artificial intelligence engineers to have a complete understanding of the version control and teh development process for Massive Data systems.

This lecture note is a framework on how to work with Git and help you quickly kick-start your own projects. The Objectives of this lecture note are

1. What is git and how it differs from other tools
2. How to install and configure Git
3. How to use Git for version control
4. How to use Git for collaboration
5. How to use Git for deployment
6. How to use Git for Continuous Integration
7. How to use Git for Continuous Deployment
8. To cover all the topics needed to know in order to use Git properly

1 What is version control? What is Git?

Version control is a method used to manage changes made to a system. While it’s commonly associated with software development, it can be applied to many other fields, like document editing or design work.

Even if you’ve never used tools like Git before, you’ve likely practiced some form of version control without realizing it. For example, a common (but not ideal) approach in software development is saving a local copy of a program when it reaches a stable state, labeling it as “stable,” and then continuing to make changes in another copy.

This manual process is something most software engineers have done before using dedicated version control tools. If you’ve done this yourself, don’t feel bad—it’s a natural first step. In fact, it’s better than leaving vague comments in the code like:

# First version
def foo(bar):
    return bar + 1

# Second version
def foo(bar):
    return bar - 1

# Current version
def foo(bar):
    return bar * 2

My Life Story Before Git

1.1 What Are Version Control Systems?

Version control systems (VCS) are tools designed to help manage changes in a structured and efficient way. They provide several key features:

1. Reversibility:
   • This is one of the most important capabilities of a VCS. It allows developers to return to any previous version of the code, which is especially useful when a bug is introduced, and the project needs to revert to a stable state.
2. Concurrency:
   • VCS tools enable multiple people to work on the same project simultaneously. This feature makes it easier to integrate changes made by different developers, even when they are working on the same files.
3. Annotation:
   • VCS tools allow developers to add explanations for their changes. This could include a summary of the modifications, the reasons behind them, or a description of the current stability of the code. Annotations provide important context for future collaborators or even your future self!

By addressing these challenges, VCS tools solve a major problem in software development: the fear of making changes. You’ve probably heard the phrase, “If it works, don’t change it.” While this might sound like a joke, it reflects how many developers feel. A good VCS helps eliminate this fear by providing a safety net, making it easier to experiment and improve your code.

1.2 Types of Version Control Systems

There are different models for version control systems, depending on how changes are saved and shared:

1. Local Version Control Systems:
   • A manual process, like saving multiple versions of files on your computer, can be considered a simple local version control system. However, this method is limited because the changes are only stored locally and can’t be easily shared or synchronized with others.
2. Distributed Version Control Systems (DVCS):
   • Tools like Git are examples of DVCS. In this model, every developer has a full copy of the repository on their local machine, while the main repository is hosted in the cloud. This setup allows for better collaboration, as developers can work offline and synchronize their changes later.

Let’s dive deeper into the features and benefits of distributed version control systems like Git.

2 Git vs SVN (DVCS vs CVCS)

2.1 Centralized vs. Distributed Version Control Systems

Before distributed version control systems (DVCS) became popular, the most widely used version control system was Apache Subversion (SVN). SVN is an example of a centralized version control system (CVCS).

2.1.1 How Centralized Version Control Works

In a CVCS, there is a single full copy of the repository stored on a central server. Developers connect to this server to save their changes. While this setup is better than a local-only version control system (which doesn’t support teamwork), it comes with some major drawbacks:

1. Dependency on the Central Server:
   • If the central server or the connection to it goes down, developers can’t save their changes.
   • Even worse, if the central repository becomes corrupted and there’s no backup, the entire version history could be lost.
2. Performance Issues:
   • Since every change must be recorded directly on the remote server, the speed of the system depends heavily on the network connection.
   • This can make the process of saving changes slower, especially in environments with poor connectivity.

2.2 Why Distributed Version Control Systems (DVCS) Are Better

Unlike CVCS, DVCS tools like Git give every developer a full copy of the repository on their local machine. This eliminates the dependency on a central server for most tasks and introduces several advantages:

1. Work Offline:
   • Developers can save changes locally at any time, even if the central server is down or unavailable.
   • The changes can be synchronized with the shared repository once the connection is restored.
2. Faster Performance:
   • Since changes are made locally, they rely on disk access rather than network speed. In most situations, this makes DVCS tools significantly faster than CVCS tools.
3. Greater Flexibility:
   • A remote server is only needed for sharing changes with others, not for saving or managing versions locally.

2.3 Key Difference

The primary distinction between CVCS and DVCS is how they handle the dependency on a central server:

• CVCS: Completely reliant on a remote server for saving and managing changes.
• DVCS: Treats the remote server as an optional way to share changes, enabling developers to work independently.

3 Download and install Git

• Right click on the links below and open them in a new tab to visit the download the software.
• Git
  • The software that allows us to do version control.
  • Like the “Track Changes” feature from Microsoft Word, but more rigorous, powerful, and scaled up to multiple files.
• GitHub
  • Hosting service for git projects — essentially Dropbox for git projects.
  • You can host remote repositories on GitHub.
  • You edit and work on your content in your local repository on your computer, and then you send your changes to the remote.
  • Through the Command Line Interface (CLI) using Github-CLI or Git Bash.
  • You can interact with Git using the Graphical User Interface (GUI) provided by GitHub Desktop
  • You can also use third-party GUIs like Tower Git or GitKraken.
• I like Git CLI and GitKraken, both are available through Github Education
• Install VSCode from here or Antigravity from here if you don’t have it already. We will use VScode as our main code editor, you can use anything you are comfortable with.

3.1 GitHub Configuration

3.2 Setting up Git

• As a first-time set-up, you need to tell Git who you are
• Open Git Bash and type the following commands:
  • In case of Windows, open Windows terminal and type Git Bash
  • In case of Mac, open terminal and type Git Bash
• Enter (type don’t copy and paste) these lines one by one (with appropriate changes):
  • Go to your GitHub account email page and copy your name and email address
  • use the one that looks like 487492+yourusername@users.noreply.github.com

git config --global user.name "Nakul Padalkar" 
git config --global user.email "2807210+nakulpadalkar@users.noreply.github.com "

• Make sure that you include here the same email you used for signing up on GitHub.
• Test if this worked by typing
• You only need to do this once on each computer you use once.

git config --list

3.3 SSH key generation & setup

1. Check if your computer is already connected to GitHub

ssh -T git@github.com

2. If it gives an error, then you’re not connected.
3. Check what key pairs already exist on your computer.

ls -al ~/.ssh

4. If SSH has been set up on the computer you’re using, the public and private key pairs will be listed.
5. The file names are either id_ed25519/id_ed25519.pub or id_rsa/id_rsa.pub depending on how the key pairs were set up.
6. If they don’t exist on your computer, use procedure on the next slide to create them.

3.4 Generating SSH Keys

5. Use following lines on command line or bash to generate your keys

Windows

• Run windows Terminal, Powershell, or command line.
• ssh-keygen
• you will be asked to specify file location. Hit Enter on keyboard, this will use default location.
• Once the key is generated you will be asked to generate a passphrase. You can skip this by hitting Enter on keyboard.
• Repeat the passphrase if you entered one, if not then hit Enter again.
• This will generate the key for your computer

MacOS

• Open a Terminal window. in Macintosh operating systems, find Terminal in the Dock or in the Utilities folder.
• Enter the following command: ssh-keygen -b 2048 -t rsa -C "your_username".
• Make sure to replace your_username with your own value.
  • Example: ssh-keygen -b 2048 -t rsa -C "jsmith".
  • Select enter and follow prompts.
  • A passphrase isn’t required. Supply a passphrase or leave blank and select enter to continue.
• When successfully generated, you see these messages:
  • Your identification has been saved in filename.
  • Your public key has been saved in filename.pub.
• Search for the public and private key files in Finder.
• The two key files are named id_rsa and id_rsa.pub.

3.5 Adding SSH key to GitHub

• Now that we have generated the SSH keys, we will find the SSH files when we check.

ls -al ~/.ssh

• Follow the steps at add the SSH key to GitHub.
• Copy the public key to GitHub

cat ~/.ssh/id_ed25519.pub

3.6 Adding SSH key to GitHub

• Now that we’ve set that up, let’s check our authentication again from the command line.

ssh -T git@github.com

It should say,

Hi <Your Name>! You have successfully authenticated, but GitHub does not provide shell access.

4 Git Usage

In this section, we’ll explore how to use Git for version control in your projects. You’ll learn how to create repositories, manage changes with commits, view history, work with branches, and resolve conflicts. We’ll also cover advanced features like tagging and undoing changes.

4.1 Creating a Repository

A repository is a directory where Git tracks changes to your files. To create a new repository, navigate to your desired directory and initialize Git:

# Initialize a new Git repository
!git init

Once initialized, a hidden .git folder is created. This folder contains all the metadata for your repository. It’s important not to modify anything inside this folder unless you are well-versed in Git.

4.2 Creating the History: Commits

Commits are snapshots of your repository at specific points in time. Each commit records the state of your files and allows you to revert to that state in the future.

4.2.1 Staging Files for Commit

Before committing changes, you need to stage them. Staging allows you to choose which files to include in a commit. Let’s create a file and check the repository status:

# Create a new file and add content
!echo 'My first commit!' > README.txt

# Check the repository status
!git status

Git will show the following output:

On branch master
Initial commit
Untracked files:
  (use "git add <file>..." to include in what will be committed)
  README.txt
nothing added to commit but untracked files present (use "git add" to track)

This means that README.txt is untracked. To stage it for commit, use the git add command:

# Stage the file for commit
!git add README.txt

# Check the repository status again
!git status

Now the file is staged and ready to be committed.

4.2.2 Making a Commit

To save changes, create a commit with a descriptive message:

# Commit the staged file
!git commit -m "Initial commit with README.txt"

This creates a new snapshot in the repository history. Each commit is uniquely identified by a SHA1 hash.

4.2.3 Adding All Changes

To stage all changes in the current directory, use:

# Add all changes
!git add .

this will add all the changes in the current directory to the staging area. if you altered a file after it was added to the staging area, git graph will require you to create “new” commit and it will appear with different Hash.

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#89CFF0',
      'primaryTextColor': '#000000',
      'primaryBorderColor': '#003366',
      'lineColor': '#003366',
      'secondaryColor': '#ffffff',
      'secondaryTextColor': '#006100'
    }
  }
}%%
    gitGraph
       commit id: "Head"
       commit
       commit

4.3 Viewing the History

To view the commit history of your repository, use the git log command:

# View the commit history
!git log

For a more visual representation, you can use the following command to display a graph of commits:

# Display a commit graph
!git log --all --graph --decorate --oneline

4.4 Independent Development Lines: Branches

Git allows you to work on branches, which are independent paths of development. By default, your repository starts on the master branch. You can create and switch to a new branch as follows:

# Create and switch to a new branch
!git branch develop
!git checkout develop

Now, all commits will be added to the develop instead of master.

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#89CFF0',
      'primaryTextColor': '#000000',
      'primaryBorderColor': '#003366',
      'lineColor': '#003366',
      'secondaryColor': '#ffffff',
      'secondaryTextColor': '#006100'
    }
  }
}%%
    gitGraph
       commit id: "Head"
       commit
       commit
       branch develop
       commit
       commit
       commit
       checkout main
       commit
       commit

4.4.1 Example: Isolating Changes in a Branch

Let’s make changes in develop:

# Modify the file and commit changes
!echo 'Changes in develop' >> README.txt
!git add README.txt
!git commit -m "Changes in develop"

Switching back to master will show the previous state of the repository:

# Switch back to master
!git checkout master

4.5 Combining Histories: Merging Branches

To merge changes from one branch into another, switch to the destination branch and use the git merge command:

# Merge develop into master
!git checkout master
!git merge develop

Git may perform a fast-forward merge, where the branch history is linear. To preserve the history as a tree, use:

# Merge with no fast-forward
!git merge --no-ff develop

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#89CFF0',
      'primaryTextColor': '#000000',
      'primaryBorderColor': '#003366',
      'lineColor': '#003366',
      'secondaryColor': '#ffffff',
      'secondaryTextColor': '#006100'
    }
  }
}%%
    gitGraph
       commit
       commit
       branch develop
       commit
       commit
       commit
       checkout main
       commit
       commit
       merge develop
       commit
       commit

4.6 Resolving Merge Conflicts

Conflicts occur when changes in two branches overlap. Let’s simulate a conflict:

# In develop
!git checkout develop
!echo 'Conflict in develop' >> file.txt
!git add file.txt
!git commit -m "Conflict in develop"

# In master
!git checkout master
!echo 'Conflict in master' >> file.txt
!git add file.txt
!git commit -m "Conflict in master"

# Try merging
!git merge develop

Git will display a conflict message:

CONFLICT (content): Merge conflict in file.txt
Automatic merge failed; fix conflicts and then commit the result.

Open the conflicted file and resolve the differences by choosing one version or combining changes. Once resolved, add the file and complete the merge:

# Add the resolved file and commit
!git add file.txt
!git commit

4.7 Tagging Important Points

Tags mark specific milestones in your repository, such as releases. To create a tag:

# Create an annotated tag
!git tag -a v1.0 -m "Version 1.0 release"

List all tags with:

# List tags
!git tag

4.8 Undoing Changes

Git allows you to undo changes at various levels:

1. Modify the Last Commit:

   # Amend the last commit
   !git commit --amend -m "Updated commit message"

2. Discard Changes:

   # Discard uncommitted changes
   !git checkout -- file.txt

3. Delete Commits:

   # Remove the last commit
   !git reset --hard HEAD~1

5 Using GitHub to manage your repositories

5.1 Setting up Github Education Account

Step 1: Go to the GitHub website:

• GitHub Sign-up

5.2 Signing up

• Fill in the following details:
  • Email Address - Provide a valid email address.
    • Use your personal email address, not your university email address.
    • We will add your university email address later.
  • Password - Create a strong password.
  • Username - Choose a unique username for your account.
  • Select the Start Puzzle button to do so, and then follow the prompts.

5.3 Verifying your account

1. GitHub will send a verification email to the address you provided.
2. Next, GitHub sends a launch code to your email address. Type that launch code in the Enter code dialog, and then press Enter.
3. After you verify your account, select the Create account button.

5.4 Choose Your Plan

1. After email verification, GitHub will ask you to choose a plan:
   • Free - For personal projects and open source contributions.
   • Paid - For additional features like private repositories for teams.
   • Most people start with the free plan: GitHub Pricing.
2. Let’s Set-up Github Education Benefits: GitHub Education

6 Using the command line (CLI)

You can interact with git and github using command line interface (CLI). It is an alternative way to interact with Git and GitHub without using a graphical interface. The command line provides more control and flexibility for advanced users.

For Beginners, it’s recommended to start with a GUI like GitHub Desktop or GitKraken, in our case VSCode. However, as you become more comfortable with Git, learning the command line can be very beneficial.

6.1 Working on local machine

• Clone the repository

git clone URL
git clone https://github.com/nakulpadalkar/git-tutorial.git

• Stage your files

git add .

• Commit your change

git commit -m "Add example code"

• Push your changes

git push

6.2 Adding your files to git repository

7 Working with GitHub in VS Code

GitHub is a cloud-based service for storing and sharing source code. Using GitHub with Visual Studio Code lets you share your source code and collaborate with others right within your editor. There are many ways to interact with GitHub, for example, via their website at https://github.com or the Git command-line interface (CLI), but in VS Code, the rich GitHub integration is provided by the GitHub Pull Requests and Issues extension.

Note

If you’re new to source control or want to learn more about VS Code’s basic Git support, you can start with the Source Control Overview topic.

7.1 Prerequisites

To get started with GitHub in VS Code, you need:

• Git is installed on your computer. Install Git version 2.0.0 or later on your machine.

• A GitHub account.

• The GitHub Pull Requests and Issues extension installed in VS Code.

• When you commit changes, Git uses your configured username and email. You can set these values with:

  git config --global user.name "Your Name"
  git config --global user.email "your.email@example.com"

7.2 Getting started with GitHub Pull Requests and Issues

Once you’ve installed the GitHub Pull Requests and Issues extension, you’ll need to sign in.

1. Select the GitHub icon in the Activity Bar
2. Select Sign In and follow the prompts to authenticate with GitHub in the browser

Screenshot of the GitHub view, showing the sign in button.

1. You should be redirected back to VS Code

If you are not redirected to VS Code, you can add your authorization token manually:

1. In the browser window, copy your authorization token
2. In VS Code, select Signing in to github.com… in the Status Bar
3. Paste the token and press kbstyle(Enter) to complete the sign-in process

7.3 Setting up a repository

7.3.1 Cloning a repository

You can search for and clone a repository from GitHub using the Git: Clone command in the Command Palette (kb(workbench.action.showCommands)) or by using the Clone Repository button in the Source Control view (available when you have no folder open).

From the GitHub repository dropdown you can filter and pick the repository you want to clone locally.

Screenshot showing the GitHub repository Quick Pick filtered on microsoft/vscode.

7.3.2 Authenticating with an existing repository

Enabling authentication through GitHub happens when you run any Git action in VS Code that requires GitHub authentication, such as pushing to a repository that you’re a member of or cloning a private repository. You don’t need to have any special extensions installed for authentication; it is built into VS Code so that you can efficiently manage your repository.

When you perform an action that requires GitHub authentication, VS Code prompts you to sign in. Follow the steps to sign into GitHub and return to VS Code.

Screenshot showing the GitHub authentication dialog.

Signing in with a personal access token (PAT) is only supported with GitHub Enterprise Server. If you’re using GitHub Enterprise Server and want to use a PAT, you can select Cancel on the sign in prompts until you are prompted for a PAT.

Note that there are several ways to authenticate to GitHub, including using your username and password with two-factor authentication (2FA), a personal access token, or an SSH key. See About authentication to GitHub for more information and details about each option.

[!NOTE] If you’d like to work on a repository without cloning the contents to your local machine, you can install the GitHub Repositories extension to browse and edit directly on GitHub.

7.4 Editor integration (optional)

7.4.1 Hovers

When you have a repository open and a user is @-mentioned (for example, in a code comment), you can hover over that username and see a GitHub-style hover with the user’s details.

Screenshot showing a user hover for a @-mentioned user in a code comment.

There is a similar hover for #-mentioned issue numbers, full GitHub issue URLs, and repository specified issues.

Screenshot showing a hover for a #-mentioned issue number in a code comment.

7.4.2 Suggestions

User suggestions are triggered by typing the “@” character and issue suggestions are triggered by typing the “#” character. Suggestions are available in the editor and in the Source Control commit message input box.

GIF showing User and Issue suggestions in the editor.

The issues that appear in the suggestion can be configured with the GitHub Issues: Queries (setting(githubIssues.queries)) setting. The queries use the GitHub search syntax.

You can also configure which file types show these suggestions by using the settings GitHub Issues: Ignore Completion Trigger (setting(githubIssues.ignoreCompletionTrigger)) and GitHub Issues: Ignore User Completion Trigger (setting(githubIssues.ignoreUserCompletionTrigger)). These settings take an array of language identifiers to specify the file types.

// Languages that the '#' character should not be used to trigger issue completion suggestions.
"githubIssues.ignoreCompletionTrigger": [
  "python"
]

7.5 Pull requests

From the Pull Requests view you can view, manage, and create pull requests.

Screenshot showing the Pull Request view.

The queries used to display pull requests can be configured with the GitHub Pull Requests: Queries (setting(githubPullRequests.queries)) setting and use the GitHub search syntax.

"githubPullRequests.queries": [
    {
        "label": "Assigned To Me",
        "query": "is:open assignee:${user}"
    },

7.5.1 Creating pull requests

Once you have committed changes to your fork or branch, you can use the GitHub Pull Requests: Create Pull Request command or the Create Pull Request button in the Pull Requests view to create a pull request.

Screenshot showing the Create Pull Request button in the Pull Request view.

A new Create view will be displayed where you can select the base repository and base branch you’d like your pull request to target as well as fill in the title and description. If your repository has a pull request template, this will automatically be used for the description.

Use the buttons in the action bar at the top to add Assignees, Reviewers, Labels and a Milestone.

Screenshot showing the Create Pull Request view.

The Create button menu allows you to select alternative create options, such as Create Draft or enable an Auto-Merge method.

Once you select Create, if you have not already pushed your branch to a GitHub remote, the extension will ask if you’d like to publish the branch and provides a dropdown to select the specific remote.

The Create Pull Request view now enters Review Mode, where you can review the details of the PR, add comments, and merge the PR once it’s ready. After the PR is merged, you’ll have the option to delete both the remote and local branch.

Note

Use AI to generate a PR title and description, based on the commits that are included in the PR. Select the sparkle icon next to the PR title field to generate a PR title and description.

Screenshot that shows the Generate Commit Message in the commit message input box.

7.5.2 Reviewing

Pull requests can be reviewed from the Pull Requests view. You can assign reviewers and labels, add comments, approve, close, and merge all from the pull request Description.

Pull Request Description editor

From the Description page, you can also easily checkout the pull request locally using the Checkout button. This will switch VS Code to open the fork and branch of the pull request (visible in the Status Bar) in Review Mode and add a new Changes in Pull Request view from which you can view diffs of the current changes as well as all commits and the changes within these commits. Files that have been commented on are decorated with a diamond icon. To view the file on disk, you can use the Open File inline action.

Changes in Pull Request view

The diff editors from this view use the local file, so file navigation, IntelliSense, and editing work as normal. You can add comments within the editor on these diffs. Both adding single comments and creating a whole review is supported.

When you are done reviewing the pull request changes you can merge the PR or select Exit Review Mode to go back to the previous branch you were working on.

Note

You can also use AI to perform a code review of the PR before you create it. Select the Code Review button in the GitHub Pull Request view.

7.6 Issues

7.6.1 Creating issues

Issues can be created from the + button in the Issues view and by using the GitHub Issues: Create Issue from Selection and GitHub Issues: Create Issue from Clipboard commands. They can also be created using a Code Action for “TODO” comments. When creating issues, you can take the default description or select the Edit Description pencil icon in the upper right to bring up an editor for the issue body.

Create Issue from TODO

You can configure the trigger for the Code Action using the GitHub Issues: Create Issue Triggers (setting(githubIssues.createIssueTriggers)) setting.

The default issue triggers are:

"githubIssues.createIssueTriggers": [
  "TODO",
  "todo",
  "BUG",
  "FIXME",
  "ISSUE",
  "HACK"
]

7.6.2 Working on issues

From the Issues view, you can see your issues and work on them.

Issue view with hover

Issue view with hover

By default, when you start working on an issue (Start Working on Issue context menu item), a branch will be created for you, as shown in the Status Bar in the image below.

Work on Issue

The Status Bar also shows the active issue and if you select that item, a list of issue actions are available such as opening the issue on the GitHub website or creating a pull request.

Issue Status Bar actions

You can configure the name of the branch using the GitHub Issues: Issue Branch Title (setting(githubIssues.issueBranchTitle)) setting. If your workflow doesn’t involve creating a branch, or if you want to be prompted to enter a branch name every time, you can skip that step by turning off the GitHub Issues: Use Branch For Issues (setting(githubIssues.useBranchForIssues)) setting.

Once you are done working on the issue and want to commit a change, the commit message input box in the Source Control view will be populated with a message, which can be configured with GitHub Issues: Working Issue Format SCM (setting(githubIssues.workingIssueFormatScm)).

7.7 GitHub Repositories extension

The GitHub Repositories extension lets you quickly browse, search, edit, and commit to any remote GitHub repository directly from within Visual Studio Code, without needing to clone the repository locally. This can be fast and convenient for many scenarios, where you just need to review source code or make a small change to a file or asset.

GitHub Repositories extension

7.7.1 Opening a repository

Once you have installed the GitHub Repositories extension, you can open a repository with the GitHub Repositories: Open Repository… command from the Command Palette (kb(workbench.action.showCommands)) or by clicking the Remote indicator in the lower left of the Status Bar.

Remote indicator in the Status Bar

When you run the Open Repository command, you then choose whether to open a repository from GitHub, open a Pull Request from GitHub, or reopen a repository that you had previously connected to.

If you haven’t logged into GitHub from VS Code before, you’ll be prompted to authenticate with your GitHub account.

GitHub Repository extension open repository dropdown

You can provide the repository URL directly or search GitHub for the repository you want by typing in the text box.

Once you have selected a repository or Pull Request, the VS Code window will reload and you will see the repository contents in the File Explorer. You can then open files (with full syntax highlighting and bracket matching), make edits, and commit changes, just like you would working on a local clone of a repository.

One difference from working with a local repository is that when you commit a change with the GitHub Repository extension, the changes are pushed directly to the remote repository, similar to if you were working in the GitHub web interface.

Another feature of the GitHub Repositories extension is that every time you open a repository or branch, you get the up-to-date sources available from GitHub. You don’t need to remember to pull to refresh as you would with a local repository.

The GitHub Repositories extension supports viewing and even committing LFS-tracked files without needing to install Git LFS (Large File System) locally. Add the file types you want tracked with LFS to a .gitattributes file, then commit your changes directly to GitHub using the Source Control view.

7.7.2 Switching branches

You can easily switch between branches by clicking on the branch indicator in the Status Bar. One great feature of the GitHub Repositories extension is that you can switch branches without needing to stash uncommitted changes. The extension remembers your changes and reapplies them when you switch branches.

Branch indicator on the Status Bar

7.7.3 Remote Explorer

You can quickly reopen remote repositories with the Remote Explorer available on the Activity bar. This view shows you the previously opened repositories and branches.

Remote Explorer view

7.7.4 Create pull requests

If your workflow uses Pull Requests, rather than direct commits to a repository, you can create a new PR from the Source Control view. You’ll be prompted to provide a title and create a new branch.

Create a Pull Request button in the Source Control view

Once you have created a Pull Request, you can use the GitHub Pull Request and Issues extension to review, edit, and merge your PR as described earlier in this topic.

7.7.5 Virtual file system

Without a repository’s files on your local machine, the GitHub Repositories extension creates a virtual file system in memory so you can view file contents and make edits. Using a virtual file system means that some operations and extensions which assume local files are not enabled or have limited functionality. Features such as tasks, debugging, and integrated terminals are not enabled and you can learn about the level of support for the virtual file system via the features are not available link in the Remote indicator hover.

Remote indicator hover with features are not available link

Extension authors can learn more about running in a virtual file system and workspace in the Virtual Workspaces extension author’s guide.

7.7.6 Continue working on

Sometimes you’ll want to switch to working on a repository in a development environment with support for a local file system and full language and development tooling. The GitHub Repositories extension makes it easy for you to:

• Create a GitHub codespace (if you have the GitHub Codespaces extension).
• Clone the repository locally.
• Clone the repository into a Docker container (if you have Docker and the Microsoft Container Tools extension installed).

To switch development environments, use the Continue Working On command, available from the Command Palette (kb(workbench.action.showCommands)) or by clicking on the Remote indicator in the Status Bar.

Continue Working On command in Remote dropdown

If you are using the browser-based editor, the “Continue Working On” command has the options to open the repository locally or within a cloud-hosted environment in GitHub Codespaces.

Continue Working On from web-based editor

The first time that you use Continue Working On with uncommitted changes, you will have the option to bring your edits to your selected development environment using Cloud Changes, which stores your pending changes on the same VS Code service used for Settings Sync.

These changes are deleted from our service once they are applied to your target development environment. If you choose to continue without your uncommitted changes, you can always change this preference later by configuring the setting "workbench.cloudChanges.continueOn": "prompt".

In the event that your pending changes are not automatically applied to your target development environment, you can view, manage, and delete your stored changes using the Cloud Changes: Show Cloud Changes command.

8 Branching Strategies (Advanced Topic)

8.1 Expanding Strategies and Practical Applications

Effective branching strategies are key to maintaining organization and collaboration in software projects. Whether the project requires a single production-ready version or multiple parallel versions, Git’s flexible branch management allows teams to tailor workflows to their needs.

8.2 Long-Running Branches

This strategy is designed for projects where maintaining a single stable version is critical. The master branch acts as the production branch, receiving updates only from thoroughly tested development branches. Meanwhile, feature branches isolate new functionality until it’s ready for integration. This strategy supports a clear distinction between development and production environments. In this strategy, the repository has a master branch used for production and separate development branches for feature work or testing. The production branch remains stable and receives updates only after extensive testing and merging from development branches. This strategy is ideal for ensuring stability in projects with frequent releases.

8.2.1 Workflow:

1. The master branch is used for developing common features applicable to all versions.
2. Once a feature is completed, it is selectively merged into version-specific branches (e.g., v1.0, v2.0).
3. Bug fixes for a specific version are handled in temporary branches (e.g., fix-bug-v1), which are then merged back into the corresponding version branch.

8.2.2 Example:

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#89CFF0',
      'primaryTextColor': '#000000',
      'primaryBorderColor': '#003366',
      'lineColor': '#003366',
      'secondaryColor': '#ffffff',
      'secondaryTextColor': '#006100'
    },
  'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': false}}
}%%
      gitGraph
        commit
        branch hotfix
        checkout hotfix
        commit
        branch develop
        checkout develop
        commit id:"ash" tag:"abc"
        branch featureB
        checkout featureB
        commit type:HIGHLIGHT
        checkout main
        checkout hotfix
        commit type:NORMAL
        checkout develop
        commit type:REVERSE
        checkout featureB
        commit
        checkout main
        merge hotfix
        checkout featureB
        commit
        checkout develop
        branch featureA
        commit
        checkout develop
        merge hotfix
        checkout featureA
        commit
        checkout featureB
        commit
        checkout develop
        merge featureA
        branch release
        checkout release
        commit
        checkout main
        commit
        checkout release
        merge main
        checkout develop
        merge release

This workflow isolates changes, ensuring that the production branch is always in a deployable state.

8.3 One Version, One Branch

In projects supporting multiple concurrent versions, this strategy ensures that each version has its own branch for ongoing updates, bug fixes, and new features. For example, an organization maintaining v1.0 and v2.0 of software can apply updates independently to each version while continuing development on the main branch. This strategy supports multiple software versions simultaneously. Each version (e.g., v1.0, v2.0) has its own branch. Updates like bug fixes or features can be applied to specific versions without affecting others.

8.3.1 Workflow:

1. Features are developed in the master branch.
2. After testing, features are selectively merged into version-specific branches.
3. If a bug affects only one version, a temporary branch (e.g., fix-bug-v1) is created, fixed, and merged back into the affected version branch.

8.3.2 Example:

%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#89CFF0',
      'primaryTextColor': '#000000',
      'primaryBorderColor': '#003366',
      'lineColor': '#003366',
      'secondaryColor': '#ffffff',
      'secondaryTextColor': '#006100'
    },
  'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showBranches': false}}
}%%


gitGraph
  commit id: "Repository init"
  commit
  branch version1
  branch bugfix-v1
  branch version2
  branch bugfix-v2
  branch version3
  branch bugfix-v3
  checkout bugfix-v1
  commit
  commit
  commit
  checkout main
  merge bugfix-v1
  commit
  checkout version1
  commit id: "feature 1 (modules): ..."
  commit id: "test feature 1 (modules): ..."
  checkout main
  merge version1
  commit id: "fix(api): ..."
  commit id: "ci: ..."
  commit
  commit
  checkout bugfix-v2
  commit
  commit
  commit
  checkout main
  merge bugfix-v2
  commit
  checkout version2
  commit id: "feature 2 (modules): ..."
  commit id: "test feature 2 (modules): ..."
  checkout main
  merge version2
  commit id: "fix(api): ..."
  commit id: "ci: ..."
  commit
  commit
  checkout bugfix-v3
  commit
  commit
  commit
  checkout main
  merge bugfix-v3
  commit
  checkout version3
  commit id: "feature 3 (modules): ..."
  commit id: "test feature 3 (modules): ..."
  checkout main
  merge version3
  commit id: "fix(api): ..."
  commit id: "ci: ..."
  commit

This strategy is common in software requiring long-term support for older versions while continuing development on newer releases.

8.4 One Branch for Each Bug

Regardless of the primary branching strategy, creating a separate branch for each bug fix is a best practice. By isolating bug fixes in dedicated branches, developers can test and resolve issues without affecting ongoing work in other branches. Regardless of your chosen strategy, creating a dedicated branch for each bug ensures isolated fixes and detailed tracking. Use naming conventions like issue-<id> for clarity. This approach minimizes the risk of overlapping changes and simplifies testing.

8.4.1 Key Benefits:

• Better traceability between bugs and their fixes.
• Isolated fixes prevent unintended side effects on other branches.

9 Remote Repositories

9.1 Leveraging Remote Repositories for Collaboration

Remote repositories facilitate team collaboration by hosting a central version of the codebase. Platforms like GitHub, GitLab, and Bitbucket enable distributed teams to share updates, review changes, and synchronize their work efficiently. The remote repository acts as the definitive source of truth for the project.

9.2 Writing Changes to a Remote Repository

To start collaborating, you must first link your local repository to a remote repository. Once linked, you can push changes to share your work or pull updates to synchronize with the team. To collaborate effectively, you need to link your local repository to a remote hosting platform like GitHub, GitLab, or Bitbucket. This enables sharing and syncing code with other team members.

9.2.1 Steps to Push Changes:

1. Create a remote repository on your hosting platform (e.g., GitHub).
2. Add the remote repository URL to your local repository:

git remote add origin <repository-url>

3. Push your local changes to the remote:

git push -u origin master

The -u flag sets the remote as the default for future pushes.

9.3 Cloning a Repository

Cloning is the process of creating a local copy of a remote repository. This allows you to begin contributing to the project immediately, with the local repository linked to its remote counterpart. Cloning creates a local copy of a remote repository:

git clone <repository-url>

This sets up a linked local repository, allowing you to start working on the project immediately.

9.4 Fetching and Pulling Changes

Git provides two commands for synchronizing with a remote repository: - git fetch retrieves updates from the remote repository without affecting your local branch. - git pull combines fetch and merge, immediately updating your local branch with changes from the remote. Fetching retrieves updates from the remote repository without merging them:

git fetch

To fetch and merge updates in one step, use:

git pull

These commands keep your local repository synchronized with the remote.

9.5 Resolving Remote Conflicts

Conflicts occur when multiple developers make changes to the same lines of code. Resolving conflicts involves integrating changes while ensuring no work is lost. This process requires careful review and testing. Conflicts occur when your changes collide with updates in the remote repository. Resolve conflicts by: 1. Pulling the latest changes:

git pull origin master

2. Fixing the conflicting files manually, staging them, and committing:

git add <file>
git commit

3. Pushing the resolved changes back to the remote:

git push origin master

This ensures everyone has the most up-to-date and conflict-free version of the project.

10 Additional Resources

1. Git Branching Model
2. Git and Github
3. Atlasian Git Tutorial

11 References

Blischak, John D, Emily R Davenport, and Greg Wilson. 2016. “A Quick Introduction to Version Control with Git and GitHub.” PLoS Computational Biology 12 (1): e1004668.

Loeliger, Jon, and Matthew McCullough. 2012. Version Control with Git: Powerful Tools and Techniques for Collaborative Software Development. " O’Reilly Media, Inc.".

McQuaid, Mike. 2014. Git in Practice. Simon; Schuster.